Skip to content

Comments

Implement namespaceOverridePaths for Fragmented Package Support#11256

Open
q4rk wants to merge 4 commits intomicrosoft:mainfrom
q4rk:fix-imports-shadowing
Open

Implement namespaceOverridePaths for Fragmented Package Support#11256
q4rk wants to merge 4 commits intomicrosoft:mainfrom
q4rk:fix-imports-shadowing

Conversation

@q4rk
Copy link

@q4rk q4rk commented Jan 30, 2026

Addresses #11257

The PR introduces a new configuration setting, namespaceOverridePaths, which allows users to explicitly define paths that should be treated as transparent namespace packages. Even if an __init__.py file is present in these paths, the import resolver will continue to search subsequent import roots for additional fragments or sub-packages.

Why

Standard Python import resolution follows a first-one-wins logic for regular packages. If an __init__.py is found, the search terminates. This causes issues in some engineering environments:

  1. Bazel & rules_python: Virtual environments are constructed by symlinking targets from multiple locations (e.g., src/, gen/, and external/). A logical package like company.core might be fragmented across these locations, with an __init__.py in the first one shadowing logical sub-modules in the others.
  2. Legacy Namespaces: Libraries using pkgutil or pkg_resources style namespaces often include an __init__.py specifically to allow merging. Pyright currently treats these as terminal, breaking discovery of sub-packages in different wheels.

What

The PR adds a new config namespaceOverridePaths. This setting allows users to define specific path prefixes that the ImportResolver should treat as transparent namespaces.

  • Updated _resolveAbsoluteImport to check against namespaceOverridePaths. If a path matches, the resolver logs the override and treats the directory as a namespace segment rather than a terminal regular package.
  • Implemented an isShadowed flag in ImportResult to track when a regular package has "claimed" a name. This ensures we maintain standard Python shadowing behavior by default (blocking the parent-directory walk fallback) unless namespaceOverridePaths are active.
  • Refined symbol aggregation: When merging namespaces across roots, implicitImports are aggregated from all fragments so that sub-modules from every root are visible in completions and from ... import ... statements.
  • Added support to pyrightconfig.json (via schema update) and VS Code settings (python.analysis.namespaceOverridePaths).
  • Updated AnalyzerService and analyzerServiceExecutor to map user-provided relative path strings to absolute URIs relative to the execution root.
  • Added full documentation in docs/configuration.md and docs/settings.md.
  • Added new test cases in importResolver.test.ts covering standard shadowing, override-enabled merging, and "triple-merge" scenarios where a namespace tunnels through multiple blockers to find a target.

@q4rk q4rk changed the title Add namespaceOverridePaths setting to configuration and settings documentation Implement namespaceOverridePaths for Fragmented Package Support Jan 30, 2026
@q4rk
Copy link
Author

q4rk commented Jan 30, 2026 via email

@q4rk q4rk marked this pull request as ready for review January 30, 2026 12:24
@q4rk q4rk marked this pull request as draft January 30, 2026 12:56
@q4rk q4rk marked this pull request as ready for review January 30, 2026 13:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant